.TH gensio_os_funcs 3 "23 Feb 2019"
.SH NAME
gensio_os_funcs \- Abstraction for some operating system functions used
by the gensio library
.SH SYNOPSIS
.B #include <gensio/gensio_os_funcs.h>
.PP
.B struct gensio_os_funcs {}
.PP
.B int gensio_default_os_hnd(int wake_sig, struct gensio_os_funcs **o)
.PP
.B int gensio_unix_funcs_alloc(struct selector_s *sel, int wake_sig,
.br
		struct gensio_os_funcs **o)
.PP
.B int gensio_win_funcs_alloc(struct gensio_os_funcs **o)
.SH "DESCRIPTION"
This structure provides an abstraction for the gensio library that
lets it work with various event libraries.  It provides the following
basic functions:
.TP
memory allocation \- Allocate and free memory.
.TP
mutexes \- Provide mutual exclusion.
.TP
file handler callbacks \- Allows file descriptors to be monitored
and report when I/O is ready on them.
.TP
timers \- Call callbacks after a certain amount of time has elapsed.
.TP
runners \- Run a function in a new execution context.  Calling callbacks
straight from user functions can result in deadlocks, this provides a
way to call callbacks from a separate context.
.TP
waiters \- Wait for operations to occur while running timers, runners
and watching for file descriptors.
.TP
logging \- Allow the gensio library to generate logs to report issues.
.PP

These are documented in the include file.

The basic issue is that there are various event handling libraries
(Tcl/Tk, glib, Xlib, custom ones, etc.) and you may want to integrate
the gensio library with one of these.  Even though it's a bit of a
pain to have to pass one of these around, it adds needed flexibility.

.B gensio_default_os_hnd
provides a way to allocate a default OS function handler for the
platform.  The same value will be returned each time, only one is
created.  You should generally use this one unless you have a special
need as documented above.

The
.I wait_sig
parameter usage on Windows is unused.  For Unix systems, this signal
is used to signal other processes that may be waiting that they need
to wake up.  This is used to wake up a process waiting on a waiter,
and it's used to signal all waiting processes if a timer is added that
is sooner than any other timer so they can adjust their waits.

If you are running your program in a single thread, you can safely
pass zero into this parameter.

If your app is multi-threaded (or, more accurately, if your app has
multiple threads that are making gensio calls) you must pass a valid
signal into this, and you must set up an empty handler for this
signal, and the signal must be blocked in all threads that call a wait
function.  You should not use this signal for anything else.  The
function that allocates a signal handler will block the signal in the
calling thread, and that sigmask is passed on to other threads it
creates.  But if you have allocated threads before allocating the os
funcs, you must make sure those other threads have this signal
blocked.

Also, if you pass in a different value to
.B gensio_default_os_hnd
than the first one you passed in, it will return
.I GE_INVAL.
You can pass in different values to
.B gensio_unix_funcs_alloc
calls, and it will use them, but there's not much value in this.  The
os funcs for Unix can share a signal handler.  And there's not much
value is multiple OS funcs, anyway.

.B gensio_unix_funcs_alloc
and
.B gensio_win_funcs_alloc
Allocate the normal os funcs for Unix and Windows based systems,
respectively.

The
.I sel
parameter for Unix allows you to create your own selector object and
pass it to the OS handler.  Passing in NULL will cause it to allocate
it's own selector object.  See the selector.h include file for details.

The
.I wake_sig
value is a signal for use by the OS functions for internal
communication between threads.  If you are running a multi-threaded
application, you must provide a valid signal that you don't use for
any other purpose, generally
.B SIGUSR1
or
.B SIGUSR2.
.SH "RETURN VALUES"
.B gensio_default_os_hnd
returns a standard gensio error.
.SH "SEE ALSO"
gensio_set_log_mask(3), gensio_get_log_mask(3), gensio_log_level_to_str(3),
gensio(5), gensio_err(3)
